Shareware Super Platinum 8

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Super Platinum 8 / Shareware Super Platinum 8.iso / mac / PROGTOOL / GO230.ZIP;1 / GO.INF < prev next >

Wrap

Text File | 1994-06-08 | 55.7 KB | 1,543 lines

GO The Install-From-Diskette Program User's Manual Copyright (C) 1991, 1994 and All Rights Reserved by -- PINNACLE SOFTWARE -- CP 386 Ville Mont Royal Quebec, Canada, H3P 3C6 ------------------------------------------------------------------------- FROM THE OXFORD ENGLISH DICTIONARY: GO, v.i. Start, depart ... with self-originated or imparted motion, from some place, position, time etc. ... always specified if it matters ... ------------------------------------------------------------------------- =========================================================================== Legal Notices =========================================================================== The GO program and related files are distributed using freeware/shareware concepts. You are entitled to use these programs for free, but certain restrictions apply. Refer to the section of this manual entitled "Versions and Registration" for details. The following products are mentioned in this manual and are trademarked or otherwise protected: PRODUCT FOR INFORMATION CONTACT ------- ----------------------- ARC System Enhancement Associates (SEA) ARCE Vernon Buerg, or System Enhancement Associates COPYQM Sydex DIET Teddy Matsumoto FORMATQM Sydex LHARC Haruyasu Yoshizaki LIST Vernon Buerg PKLITE PKWare PKUNZIP PKWare Several text editor programs are mentioned in this manual. These are trademarked or otherwise protected by their companies or authors. =========================================================================== Layout of This Manual =========================================================================== Legal Notices Layout of This Manual A Quick Overview of the GO Package Basic Concepts What is GO? How GO Works Using GO Optional Menu Lines The "Information" Selection Colorization Rules The "Install" Selection Changing the Way GO Works Doing it the Easy Way Doing It the Hard Way Small Program to Run Afterwards Intermediate Techniques Start-Up Parameters Generating an Introductory Screen Letting the User Choose the Viewing Method Information and Install Menus Menu Order Advanced Techniques Using the GO Extension of Text Files The ;INST Command Jumping From Information to Installation Overriding the Archive File Name Other Applications Multi-Disk Installation Installation Example NAMe SENDto STARt The No-Go Technique Same Package -- Different Diskette Sizes THISdisk NEWDisk NEWFile The GO-COPY Program What is GO-COPY? The GO-COPY.COP File The GO-DISKS Program What is GO-DISKS? GO-COPY and GO-DISKS Samples Using GO in Batch Files What is GO-MENU? Using GO -D With GO-MENU The GO.HDG File Changing the Menu Title Jumping Directly to the Information Menu The GetKey Alternative Hints and Tips Specifying GO-COPY File Names Renaming Copy Files Other Programs Included with GO SEE GO_SMALL READING SETERR WAITBLK WAIT GETKEY Versions and Registration Changes Between Versions Registered Usage of GO Programs Free Usage of GO Programs Ordering Upgrades to GO Standard Discount Thank-You =========================================================================== A Quick Overview of the GO Package =========================================================================== The GO package includes the following programs: GO -- Place this program on any diskette you send out which contains compressed archive files (e.g. .ZIP or .LZH). The GO program will make installation easy. This is especially important if you send disks to computer novices. GO can also display program information, or print out a reply form. GO-COPY ------- This program makes it possible for computer novices to copy selected files from your disk onto another diskette. This is handy if you are a shareware author, since you want to make your software easy to pass around. GO-DISKS -------- This program reads in a list of file names, then copies those files to diskettes. Since the files are kept in RAM during the copy, you can mass- produce disks more quickly than if you were using the COPY command. GO-MENU ------- This program is used in a batch file to display a menu of up to 18 items. This is ideal for organizing a diskette containing several unrelated programs. A much simpler "pick an option" program is also included in the GO package -- see the GETKEY program mentioned below. Other Programs -------------- The package also includes these utility programs which have proved useful in packaging software: SEE File viewer/printer GO_SMALL A compressed but fully functional version of GO.EXE READING Displays the nicely centered message "Reading disk..." SETERR Sets the DOS ErrorLevel WAIT Waits for time-out or for a key-press WAITBLK Waits for a blank diskette in the indicated drive GETKEY Waits for user to hit a key and reports result as ERRORLEVEL Each of these programs are described in more detail later. =========================================================================== Basic Concepts =========================================================================== ----------- What is GO? ----------- "GO" is an installation program. It is a specialized interface for dearchiving programs such as PKUNZIP, ARCE, LHARC and so on. You use it for distribution of software via diskette. If you've ever given a computer novice a diskette with an archived file, you know the routine: "Okay, you put the diskette in the drive, then type PKUNZIP followed by the root name of the zip and then the name of the directory it's going to, unless you're there already ... and don't forget to separate the parameters with spaces!" The usual comment after such an explanation is: "Can't you make it any easier that that?" Thanks to GO ... you can! ------------ How GO Works ------------ NOTE: In this manual, we refer to archive files as ZIP files. The shareware version of GO is initially configured to dearchive files produced by PKWare's PKZIP program, but it can also work with ARC, PAK, ZOO or other archive formats. We like to use the LZH format on some of our distribution diskettes. When you're preparing a diskette for somebody, copy one or more ZIP files (up to a maximum of 17) onto the diskette, plus the dearchiving program, plus the file GO.EXE. Then write an explanation on the diskette label: "Put diskette in the A: drive -- At the DOS prompt enter the command A:GO" If the user follows those simple instructions, he will be able to install the ZIP files that are located on the diskette. The user does require a certain minimum level of knowledge, though. He must be familiar with terms like Drive A:, File, and Directory. -------- Using GO -------- When the user types A:GO (or B:GO if appropriate) he is presented with a very simple menu that offers him the following three choices: - Information - Install - Quit He can select an option either with function keys or by using the arrow keys and Enter. <Information> displays a text file on the diskette. If there are more than one text file, he is presented with a menu. <Install> suggests a directory name (which the user can change), then dearchives the program into that directory. If there are more than one archive file, he is first presented with a menu. ------------------- Optional Menu Lines ------------------- The GO menu sometimes shows more than the three items mentioned (i.e. Information, Install and Quit). The following two items may also appear: - About "GO" - Print reply form <About "GO"> appears on all unregistered copies of GO. If you order a personalized copy of GO ($19), this advertisement will disappear. (Personalized copies also replace our copyright notice on the main menu with the text of your choice.) <Print reply form> appears only if the file GO-FORM.DAT appears on the diskette. GO-FORM.DAT is a text file that can be prepared on any standard DOS text editor. --------------------------- The "Information" Selection --------------------------- GO's Information section is designed exclusively for small text files. If you want to display a large document prior to installation, we recommend that you use the SEE program provided with GO. A "text file" is any file with an extension of TXT, LST, or S-D. The Information section is appropriate for displaying one or two screens containing important information such as: - A brief description of what's on the disk - How the user can obtain help if he gets stuck If the user is viewing the text on a color monitor, the text will be displayed in various colors, according to some simple rules. Colorization Rules ------------------ If the viewer is using monochrome or MODE BW80, all text is the same color. Otherwise... IF THE LINE CONTAINS THE COLOR IS -------------------- ------------ Regular text LightGreen unless... Four spaces in a row Yellow unless... All uppercase LightMagenta unless... Characters over ASCII 128 LightCyan unless... ;NEW or ASCII 12 in col. 1 White on Blue NOTE: ASCII 12 (CTRL-L i.e. Form Feed) causes a new screen to be displayed. All text editors have a method for inserting control characters. WordStar-style editors (QEdit, Turbo Pascal Editor, etc.) can insert Ctrl-L with the keystroke sequence Ctrl-P Ctrl-L. If you can not type a CTRL-L, you can type ;NEW instead. The advantage of using CTRL-L is that it will cause a page-eject if the document is printed out. This colorization technique is not as versatile as ANSI displays, but it allows the user to view or print the files using whatever method he prefers. Also, these colorization rules let you use a regular text file, are easily memorized, and generally create a fairly attractive display. ----------------------- The "Install" Selection ----------------------- NOTE: The "Install" selection appears on the main GO menu only if GO sees an archive file that uses the format it is configured for (e.g. a ZIP file if GO is configured to use PKUNZIP; ARC for ARCE etc.) When the user selects "Install" from the main GO menu, the archive file on the diskette is installed in a directory with the same name. (The user has a chance to change the name of the directory.) If there is more than one archive file, the user is first presented with a menu so he can select which file he wants installed. Remember to put a copy of the dearchiving program on the diskette, or the installation step will display an error message. (In such case, GO will scan the user's PATH for a copy of the dearchiving program, but it will nevertheless caution him that it expected to find a dearchiving program on the diskette. This forewarns the user that problems may occur if his copy of the dearchiver is obsolete.) After the installation is complete, GO looks in the directory for a file named INFO.GO. If GO can not find it, it looks for a file named READ.ME. If it finds either one, it displays it. If it can't find either one, it displays the first DOC file in the directory. GO then returns the user to DOS. Your INFO.GO (or READ.ME) file should tell the user what to do next. One helpful technique is to tell the user to start a batch file (named, say, START.BAT) which contains a menu (using our GO-MENU program) which looks something like this: F1 Introduction F2 User manual F3 Demonstration F4 Calling for technical support F8 View or print registration form F10 Exit Text files (e.g. the introduction and user manual) can be displayed with our SEE.EXE program (included in the GO package). If your installation is fancy (i.e. requires dearchiving the archive file into several different directories), you could place the directories in separate archive files. A better solution is to order a customized version of GO, or to modify the dearchiving parameters to retain sub-directory names. The method for modifying GO directly is explained in the next section. See also "The ;INST Command" in "Advanced Techniques". =========================================================================== Changing the Way GO Works =========================================================================== --------------------- Doing it the Easy Way --------------------- When you order a registered copy of GO from Pinnacle Software, you may ask us to change the dearchiving method and certain other items. Please remember to cite the precise name of the program that does the dearchiving, the extension of the archive files that it handles, and the command-line parameters it requires. (If possible, send us a copy of the program so we can test it.) There is no extra charge for this service (apart from the basic registration fee). For a list of the items that we can change for you at no extra charge, start up GO as follows: GO /? --------------------- Doing It the Hard Way --------------------- If you're an experienced programmer, you can use a program such as DEBUG to "zap" in the name of the dearchiving program. You can find the text string near the end of the GO.EXE file. The byte just prior to each string dictates its actual length. The string following the file name contains the extension of the archive files (e.g. ZIP). This can be changed if necessary -- be sure to change the length byte if different from the original. The next string (ten characters) contains the parameter to pass to the dearchiver. (Some dearchivers, such as PKUNZIP, don't need a parameter) For example, to change the dearchiving method from PKUNZIP to LHA... Original Hex/Ascii: 0B 50 4B 55 4E 5A 49 50 2E 45 58 45 00 00 03 5A .PKUNZIP.EXE...Z 49 50 00 00 00 00 00 00 00 00 00 00 00 00 0B 00 IP.............. After modification: 07 4C 48 41 52 43 2E 45 58 45 00 00 00 00 03 4C .LHA.EXE.......L 5A 48 01 65 00 00 00 00 00 00 00 00 00 00 00 00 ZH.e............ To summarize, the variables are laid out as follows: Dearchiving program: 1 length byte, then 12 characters for file name Archive extension: 1 length byte, then 3 characters for extension Dearchiving parameters: 1 length byte, then 10 characters for parameters After modification, you can check your work by starting GO as follows: GO /? You can also use this command to see a list of the items that we can modify for you for the cost of basic registration. ------------------------------- Small Program to Run Afterwards ------------------------------- If you start up GO with GO /? to display the items we can change for you, you will notice that one of them is "Small program to run afterwards". It is possible to run a little program after GO ends. Although this sounds like a good idea, it is not always recommended, for two reasons. First of all, GO takes up a certain amount of memory, and you never know how much RAM the end user has available. If GO calls up a large program (your main application, for example), the user may run out of memory. Second, if GO ends immediately after you display a INFO.GO file (which should tell the user what to do to get started), you are training the user how to start up your application. Since many users learn computer operations by rote (i.e. they memorize the keystrokes they type), this can save the user some confusion the next day when he tries to recall how to start the program; if he did it once before, he will probably remember. The "small program to run afterwards" is best reserved for a one-time installation or configuration program, and it should take up less than 300K of RAM when it runs. =========================================================================== Intermediate Techniques =========================================================================== ------------------- Start-Up Parameters ------------------- GO can detect if the user is using a monochrome display card, but if you know that the user has a monochrome monitor with a COLOR display card, advise him that he can improve legibility by starting up GO as follows: GO M The GO program can report on its home drive (i.e. which drive GO.EXE is located upon) if you start it up like this: GO /@ This sets the DOS ERRORLEVEL to 1 if GO.EXE is on the A: drive, 2 if it is on the B: drive, 3 if on the C: drive, and so on. This capability is helpful if you have a batch file on diskette that calls GO and needs to return to it later. Another start-up parameter (the -D parameter) is described in the section of this manual entitled "GO-MENU". For more information about start-up parameters, start GO as follows: GO /? --------------------------------- Generating an Introductory Screen --------------------------------- If you want your user to see some text even before the main menu shows up, place the text in a file named 'GO-STRT.DAT'. This is good place to put personal notes or special instructions that apply only to the recipient of the diskette. The personal note is a nice touch that your users may appreciate; most people don't expect to be greeted by name when they run the installation program! ------------------------------------------ Letting the User Choose the Viewing Method ------------------------------------------ When designing GO-viewable screens, bear in mind that the user may decide to view the file with another viewer, such as LIST or SEE. Thus, even though you may be tempted to do this: End of screen 1 <CTRL-L>Heading of Screen 2 Text of screen 2 ...you should leave at least one empty line in front of the heading: End of screen 1 <CTRL-L>Heading of Screen 2 Text of screen 2 Similarly, if you know that the file is likely to be printed, avoid using line-drawing and other special characters. ----------------------------- Information and Install Menus ----------------------------- Information and install menus pop up only when there are more than one file of the appropriate type. For example, if you had one ZIP file, it would be picked automatically when the user selects <Install> from the Main Menu. However, if there were more than one ZIP file, the user would be presented with a menu. Menu Order ---------- The text menu is sorted by extension according to the following order: TXT LST S-D (The GO extension is a special case, explained later) If you have several files with one extension, they appear in the same order that is shown in the listing obtained with the DOS DIR command. If you want to modify the list of extensions, provide us with your required list when you register GO and we'll modify your copy of the program accordingly. There is no extra charge for this service. If you want to modify the list yourself, you will find it located near the end of the EXE file. The string is 20 characters long, preceded by a length byte. For information about such alterations, refer to the section entitled "Doing It the Hard Way". The install menu lists the files in the order they appear in the listing obtained with the DOS DIR command. =========================================================================== Advanced Techniques =========================================================================== ------------------------------------- Using the .GO Extension of Text Files ------------------------------------- As mentioned earlier, the "Information" option of the main GO menu scans for these extensions: TXT LST S-D GO also looks to see if you have any files with the .GO extension. These are treated like other text files, but the first line of the file is displayed on the Information menu, instead of the file name. When the user selects the file from the Information menu, the first line of the file (the one that appeared on the Information menu) is NOT displayed. GO files support some other special features, which are explained below. ----------------- The ;INST Command ----------------- You can place an ;INST command at the end of a GO file to control the installation process. This is explained below. Jumping From Information to Installation ---------------------------------------- If the last line of a .GO file is: ;INST the user will be asked (after viewing the final screen of information): Do you want to install this now? (Y n) If they press Y, the product is installed immediately. This saves them the trouble of going back to the main menu and then selecting "Install". Overriding the Archive File Name -------------------------------- If the INST command is followed by a file root name (up to 8 characters), this will over-ride the normal association between the GO and archive file names. For example, if you have a file named WHIZ.GO which looks like this: About Whizzo-Calc ;NEW Whizzo-Calc Whizzo calc is a nifty new calculator program! ;INST WC then it would show up on the Information menu as "About Whizzo-Calc", but instead of looking for the archive file WHIZ.ZIP, it would look for WC.ZIP since the INST command specified a different root-name. Other Applications ------------------ The INST command is particularly useful in multi-disk installations. This technique is described in the following section. =========================================================================== Multi-Disk Installation =========================================================================== Sometimes there isn't enough room on a single disk for an archive file that contains the entire product to be installed. In such cases, you can break up the product into multiple archives, then use an extended form of the INST command to create a multi-disk installation. The INST command supports the following parameters: PARAMETER NAME NOTE EXAMPLE DESCRIPTION OF PARAMETER -------- ---- ----------------- ------------------------------------------ NAME 1 Name=Calc-O-Rama Actual name of the product (max 40 chars) SENDto 1 SendTo=CALCRAMA Suggested directory name (max 60 chars) STARt 2 Start=Install Name of the first disk THISdisk 3 ThisDisk=Install Name of this disk NEWDisk 4 NewDisk=Programs Name of next disk in install NEWFile 4 NewFile=CALC-2 Root name of archive file on the next disk Only the first four letters of the parameter identifier (e.g. NAME, NEWD, etc.) are required. Unless otherwise specified, the maximum length of a parameter's value is 20 characters. The character immediately following the INST command is used as a delimiter (separator) for the other options -- it is typical to use a space or a slash for this -- see the installation example. NOTE #1: Appears only on the FIRST installation disk NOTE #2: Appears only on the SECOND and subsequent installation disks NOTE #3: Appears on all disks NOTE #4: Appears on all but the last disk These parameters are explained in more detail after the example section. -------------------- Installation Example -------------------- ASSUMPTION: You have a product named "The Sapphire Bulletin Board System" (Sapphire BBS) which you have broken up into two ZIP files of approximately 200K each in order to ensure that they fit on 360K disks. Here is what would appear on each disk: -------------------------------- DISK # 1 -------------------------------- GO.EXE PKUNZIP.EXE SAPPHIR1.ZIP SAPPHIR1.GO -- This file would look something like this: About Sapphire ;NEW SAPPHIRE -- THE ZERO-MAINTENANCE BBS SAPPHIRE is a bulletin board system that is optimized for business and institutional applications. It installs in minutes and does not need daily maintenance. Sapphire is reliable, simple and safe. ;INST/Name=Sapphire BBS/ThisDisk=Docu/NewDisk=Programs/NewFile=SAPPHIR2 -------------------------------- DISK # 2 -------------------------------- GO.BAT -- This file would look something like this: ECHO OFF ECHO Please refer to the Docu disk for installation instructions. PKUNZIP.EXE SAPPHIR2.ZIP SAPPHIR2.GO -- This file would look something like this: ;INST/ThisDisk=Programs/Start=Docu -------------------------------------------------------------------------- The INST parameters are explained in more detail below. ------------------ The NAMe Parameter ------------------ (Optional; first disk) The NAMe parameter lets you specify the actual name of your product. This is used only in the question "Do you want to install [product name]?" If you do not specify this parameter, the name of the archive file will be used. -------------------- The SENDto Parameter -------------------- (Optional; first disk) The SENDto parameter lets you specify the recommended destination directory. If you do not specify this parameter, the directory will be named after the first archive file. The user can, of course, change the recommended installation directory in any case. In most cases, you should NOT specify a drive for the SENDto parameter -- GO will pick C: (or B: if the user doesn't have a C: drive). However, you can specify a drive if you want to force the user to consider a particular drive. ------------------- The STARt Parameter ------------------- (Disks 2+) The STARt parameter is used on any disks after the first one to specify the name of the first installation disk. (See THISdisk) The No-Go Technique ------------------- If the various parts of the product are on different diskettes, you only need to put GO on the first diskette. On disks 2+ you can put a simple batch file named GO.BAT which looks something like this: ECHO OFF ECHO To begin installation, please use the first disk -- not this one. ECHO The first disk is labelled [whatever]. Thus, if the user inserts the wrong disk and tries to run GO, he will be told what he should have done. You CAN put GO.EXE on disks 2+ -- it will use the STARt parameter to figure out that it's not the right disk to begin installation. However, the "No-Go Technique" (i.e. using the batch file above) uses less room on the disk, and if this saves you adding an extra disk to your package, you can save money! Same Package -- Different Diskette Sizes ---------------------------------------- The STARt parameter usually points to the name of another diskette, but it does NOT cause problems if you put several installation steps for the same product on a single disk. Look at these two methods of packaging a product: TWO 360K DISKETTES ONE 720K DISKETTE ----------------------------- ----------------- GO.EXE GO.EXE GO.BAT MYPROG1.GO MYPROG1.GO MYPROG2.GO MYPROG1.GO MYPROG1.ZIP MYPROG2.ZIP MYPROG1.ZIP MYPROG2.ZIP ----------------------------- ----------------- You could set up MYPROG1.GO and MYPROG2.GO to handle the 300K archives MYPROG1.ZIP and MYPROG2.ZIP. These could go on separate 360K diskettes, and since the second diskette contains the batch file described in "The No-Go Technique", the user will not be able to start installation on any disk other than the first. However, if you put both .GO files on the same disk (a 720K or 1.44 Meg), the user will NOT be instructed to "insert the proper disk" if he tries to begin installation with MYPROG2 -- GO checks ahead of time to see if the required starting archive is on the current disk. He will, however, be warned that he is trying to start installation in the wrong place. The user may continue with installation if he wants, but is advised against it. On the 720K diskette, step 2 (i.e. MYPROG2) will show up on the Install menu, but the user will usually not see it on his Information menu, because GO does not add a .GO file to the information menu if its first line is an ;INST command -- it assumes that it is intended for step 2 or later and thus contains no text. ---------------------- The THISdisk Parameter ---------------------- (All disks) The THISdisk parameter gives the current disk a name. This name is checked when the user inserts the disk as the next step in an installation. (See NEWDisk) The "disk name" applies only to the current installation task (i.e. the archive file plus the associated .GO file), so you could, in theory, have several GO files on the disk, each giving it a different name. That is to say, the disk itself is not "stamped" in any way; the identification is contained in the .GO file only. --------------------- The NEWDisk Parameter --------------------- (All but last disk) If there are any disks to follow the current one, you specify the disk name with the NEWDisk parameter. For example, if you name the current disk DISK3 by using "THIS=DISK3", it makes sense to name the next disk DISK4. You specify this as "NEWD=DISK4". If DISK3 is the FINAL disk, though, omit the NEWDisk parameter. This is how GO knows that the installation is complete. Before asking for a new disk, GO checks to see if the required archive is on the current disk. (See "Same Package -- Different Diskette Sizes") --------------------- The NEWFile Parameter --------------------- (All but last disk) The NEWFile parameter lets you specify the root name of the archive file to be used in the next installation step. You could, in theory, give identical file names to all archives on all installation disks. In practice, however, you will give them different names because this lets you: - Keep standard copies in the same hard drive directory - Place multi-disk installation steps ON THE SAME DISK GO always looks on the current disk for the NEWFile file before asking for a new disk. Thus, you can place your installation files on several 360K diskettes or put them all on a single 1.4 meg diskette. (See "Same Package -- Different Diskette Sizes" for an example of this technique.) =========================================================================== The GO-COPY Program =========================================================================== ---------------- What is GO-COPY? ---------------- GO-COPY processing lets the user copy selected files to another diskette. If GO sees the files GO-COPY.EXE and GO-COPY.COP on the diskette, it will read the first line of GO-COPY.COP and display that on the main GO menu. When the user selects this item, the program GO-COPY.EXE is called. GO-COPY copies files from the diskette to another diskette. The files to be copied are specified in the file GO-COPY.COP (described later). All files to be copied are first read into RAM, in order to make rapid duplication possible. This places a limit on the size of the copy task. GO and GO-COPY take up around 120K, so you need around 500K of free memory to copy a full 360K disk. If there is not enough RAM, the user is advised to remove TSRs, or to run GO-COPY directly (since GO is not loaded, this saves about 70K). -------------------- The GO-COPY.COP File -------------------- GO-COPY.COP is a text file. It has the following format: Text to appear on the main GO menu File name File name : : END Text to be displayed prior to copy task : : Up to 50 files can be copied by GO-COPY. The end of the list of files is indicated by the word END. Wildcards are permitted (e.g. *.EXE). The display text is shown according to the standard display and colorization rules described in "Basic GO Techniques". =========================================================================== The GO-DISKS Program =========================================================================== ----------------- What is GO-DISKS? ----------------- GO-DISKS processing is just like GO-COPY processing, but is designed for the software developer rather than the end user. Instead of asking you to press a key to continue, GO-DISKS monitors the status of the diskette drive. GO-DISKS is useful when you need to create dozens of copies of the same disk. Since the copies are performed from RAM, you can create the disks faster than usual. The data for GO-DISKS is kept in the text file GO-DISKS.DSK. You may also pass the name of the file on the command line. The format of GO-DISKS.DSK is the same as for the GO-COPY.COP file. IMPORTANT NOTE: GO-DISKS requires an AT-class (or higher) computer. It will not work on most XT- or PC-class machines because their diskette drives can not detect the absence of a diskette. NOTE: If you find GO-DISKS useful, you might also consider trying out the faster and more powerful COPYQM program created by Sydex Inc. We ourselves use the FORMATQM program, also by Sydex. ---------------------------- GO-COPY and GO-DISKS Samples ---------------------------- The original GO package includes sample GO-DISKS.DSK and GO-COPY.COP files. In order to try these out, enter GO-COPY or GO-DISKS at the DOS prompt. =========================================================================== Using GO in Batch Files =========================================================================== ---------------- What is GO-MENU? ---------------- The GO-MENU program is used in a batch file to display a menu of up to 18 items. This is useful for organizing a diskette containing several unrelated programs, but can be used in any batch file application. GO-MENU reads the contents of the menu from an ordinary text file containing up to 19 lines (a menu header followed by the menu lines). The user can select an item from the menu by moving a cursor bar with the arrow keys, then pressing Enter. Also, if there are 10 or less menu choices, the function keys (F1 to F10) are displayed beside each menu choice. The command line format for GO-MENU is: GO-MENU <menu file> For example: GO-MENU MYMENU.MNU For a sample menu definition, refer to the file GO-MENU.MNU, included in the GO package. It also shows how lines beginning with a semi-colon (;) are ignored (i.e. interpreted as comments). To try it out, enter this command at the DOS prompt: GO-MENU GO-MENU.MNU This demonstrates a short menu of only 10 items. A longer sample is also provided; to try it out, enter this command at the DOS prompt: GO-MENU LONG.MNU The GO-MENU Save File --------------------- You can create a "save file" to remember the last selection a user picked on 256 different menus. The format of this technique is: GO-MENU menu-file save-index save-file For example: GO-MENU LONG.MNU 123 TEST.SAV The save index is a number from 0 to 255. Each menu should have its own index. In the example above, save index 123 would remember the position of the cursor for LONG.MNU. The position is NOT saved if the user selects the LAST item on the menu, which is assumed to be "Quit" or "Previous menu". For more details, start up GO-MENU like this: GO-MENU /? ------------------------ Using GO -D With GO-MENU ------------------------ The GO program has a special command line parameter designed to work with GO-MENU. Normally, when you call GO, it will look in its home directory for an archive file. Thus, if the user is on the C: drive when they type A:GO, it will look on the A: drive, because that is where GO.EXE is located. The -D parameter, however, tells GO to look in the current directory. This lets you use a single copy of GO to support many directories. For example, your batch file might look like this: ECHO OFF REM Batch file placed in the root directory of the diskette A: :AGAIN CLS CD \ GO-MENU MYMENU.MNU IF ERRORLEVEL 4 CD \GAMES IF ERRORLEVEL 5 CD \MISC CLS \GO.EXE -D IF ERRORLEVEL 10 GOTO END GOTO AGAIN :END The line: \GO.EXE -D Executes the GO program in the root directory. The -D parameter, though, tells it to look for archives in the current directory. Note also the line: IF ERRORLEVEL 10 GOTO END If GO ends because a program was just installed, it will set the DOS ErrorLevel to 10. This lets you break out of the batch file. --------------- The GO.HDG File --------------- NOTE: In order to protect our copyright, we restrict the use of the GO.HDG file to registered copies of GO. Changing the Menu Title ----------------------- In the sample batch file shown previously, the user could "navigate" to the \GAMES and \MISC directories. It would be nice if, when the GO program was called, it would replace the title line (which is normally just a copyright message) with a title like: GAMES SECTION, or MISCELLANEOUS PROGRAMS. If GO sees a standard text file named GO.HDG in the directory, it will use the first line of the file as the title of the main menu screen. This lets you change the 35-character header to suit circumstances. Jumping Directly to the Information Menu ---------------------------------------- If the second line of the HDG file contains the three characters "INF", GO will skip the usual main menu and display only the "Information" menu. In such case, the first line will be used as the title of the "Information" menu as opposed to the main menu. This technique of skipping the opening menu is sometimes more appropriate, especially for users who are beginners. By using a combination of GO-MENU, GO -D and GO.HDG, you can create a "guided tour" of all your software products! ---------------------- The GetKey Alternative ---------------------- Sometimes you don't need a complicated menu -- just a one-line question. You can use the GETKEY program to do this. For example: GETKEY Are you sure? YN Without clearing the screen, this displays the text "Are you sure?" and the available keys (YN), then sets the DOS ERRORLEVEL to 1 if the user presses "Y" or 2 if the user presses "N". The first key listed is the default key; if the user presses spacebar or Enter, that is the key that will be selected. You can detect other characters besides Y or N. For example: GETKEY Select an option. 1234567 This would accept the keys "1" through "7", while spacebar and Enter would be interpreted as "1". (All other keys are ignored.) You can change the default key from the first one listed to one of the other keys by prefixing the desired default key with the "@" character. For example: GETKEY Select an option. 123@4567 This would accept any key from "1" to "7", while spacebar and Enter would be interpreted as "4". For a complete formal description of GETKEY, enter the following at the DOS prompt: GETKEY /? This describes some additional options, such as space-padding, and shows you how you can use GETKEY to provide a "Press space to continue" message. (See also the explanation of the WAIT program for an alternative method of displaying a "Press space to continue" message.) =========================================================================== Hints and Tips =========================================================================== ----------------------------- Specifying GO-COPY File Names ----------------------------- When you specify files in GO-COPY.COP, don't include the drive letter. For example, if you list a file like this: A:\DATA\INVOICE.DAT GO-COPY will always look at the A: drive for that directory and file. However, if you specify it this way: \DATA\INVOICE.DAT GO-COPY will look on whatever drive GO-COPY.EXE is on. This is usually the A: drive, but this will let the user run GO-COPY from any drive. ------------------- Renaming Copy Files ------------------- The files listed in GO-COPY.COP or GO-DISKS.DSK can be copied to a file with a different name. Simply specify the new name after the name of the source file. For example: \MYPROG\TEST.EXE PROGRAM.EXE This feature can not be used with wildcards. For example, the following lines would NOT be valid: \BAD\*.EXE NAUGHTY.EXE \BAD\*.DOG *.CAT =========================================================================== Other Programs Included with GO =========================================================================== The following programs are also included with GO. We've found them to be quite useful in packaging software. Please see the section entitled "Versions and Registration" for information about the distribution of these programs. --- SEE --- The SEE program displays (and optionally prints) a text file. We have included it as a document viewer for this manual. You may find it useful for your own applications. The format for SEE is: SEE <file name> For example: SEE MYFILE.TXT For complete instructions, enter this command: SEE /? SEE is a freeware program. If you distribute it, you must include the file AMAZE.TXT (our order form), and your documentation must mention this file. If you wish to avoid this requirement, you can purchase a copy of SEE for distribution purposes. Please call us for details. -------- GO_SMALL -------- This is a compressed copy of the GO.EXE program. We recommend that you use an EXE file compressor before you put your copy of GO onto the diskette; this leaves more room for software. If you don't have access to an EXE compressor, you can copy GO_SMALL.EXE to your diskette as GO.EXE. GO_SMALL is a copy of GO.EXE that was compressed with the DIET program. Since it is compressed, you can not modify it as described in the section "Doing it the Hard Way". If you want to apply modifications, you must do them to an uncompressed copy of GO.EXE. Another popular EXE compressor is PKLITE from PKWare. ------- READING ------- The READING.EXE program displays the message "Reading Disk... ". This gives the user something to look at while jumping from place to place in batch files, which are notoriously slow when run from diskettes. ------ SETERR ------ SETERR sets the DOS ErrorLevel to the specified number. The format for this command is: SETERR <number> For example: SETERR 25 SETERR is useful for controlling the flow of batch files. For example, if one file CALLs another, the called file can set an errorlevel of 0 if everything is fine, or 255 if there was an error. Thus, the batch files would look something like this: TEST.BAT OTHER.BAT -------- --------- ECHO OFF ECHO OFF CALL OTHER.BAT MYFILE.TXT IF (%1) == () GOTO PROBLEM IF ERRORLEVEL 255 GOTO PROBLEM IF EXISTS %1 GOTO OKAY ECHO Copying file... :PROBLEM COPY MYFILE.TXT A: SETERR 255 GOTO END GOTO END :PROBLEM :OKAY ECHO The file wasn't there! SETERR 0 :END :END In this way, you can write subroutines in batch files. (You can accomplish something similar using "SET" environment variables, but you run a risk: if the environment space runs out, your batch file will fail.) ------- WAITBLK ------- The WAITBLK program is a batch-file utility which lets you create an alternative to GO-DISKS processing (described earlier). WAITBLK will wait for a blank diskette to be inserted into the specified drive. For details, enter the DOS command: WAITBLK ? WAITBLK is not recommended for XT and PC machines, which typically do not report whether or not the the drive is ready. ---- WAIT ---- The WAIT program waits for the user to hit a key. If the user does not hit a key in the required amount of time, the wait "times out". This is handy for batch files that usually run unattended. For a complete description of WAIT, enter the following command at the DOS prompt: WAIT /? =========================================================================== Versions and Registration =========================================================================== ------------------------ Changes Between Versions ------------------------ If you are curious about what has changed between versions, or if you have a problem and think it might be caused by an upgrade incompatibility, refer to the version history file by entering the following command at the DOS prompt: SEE CHANGE.LOG ------------------------------- Registered Usage of GO Programs ------------------------------- To obtain a fully-registered copy of GO, order a personalized copy for just $19. To view or print an order form, make sure that you are in the GO directory then enter START. For a list of the items that you can customize, enter GO /? at the DOS prompt. There are several advantages to having a registered copy of GO: - You receive a virus-screened copy of the latest version, direct from the author. - Your main menu header (typically your company name) is stamped right into the EXE file and is checksummed to prevent alteration by pirate distributors. - You can use HDG files (see "The GO.HDG File") - Your copy of GO will have our advertising screen removed. - You are granted privileged access to our support BBS. If you are in a hurry to get your copy, you can order our "Instant Registration Service", which lets you download your registered copy from our support BBS. For complete pricing, see the order form, located in the file GO-FORM.DAT. ------------------------- Free Usage of GO Programs ------------------------- You are entitled to use the GO program to distribute your software. You don't have to pay a penny for the privilege! Why do we allow people to use our program without paying for it? Because all unregistered copies of GO contain our advertising screen (i.e. the "About GO" selection on the main menu). Thus, by passing around unregistered copies of GO, you are helping us advertise. Everybody wins! As for the other programs, you are welcome to use them under these circumstances: (A) You are a registered owner of GO, or ... (B) The program is accompanied by a unregistered copy of GO, or ... (C) The program is accompanied by the file AMAZE.TXT and your documentation explicitly states that it is included as part of the licensing requirement for the particular program. ----------------------- Ordering Upgrades to GO ----------------------- If you have already registered a copy of GO and would like to register a newer version, all further GO orders are available from Pinnacle at a minimum of 25% off the prices indicated on the order form. We sometimes offer larger discounts or special arrangements; call us if you would like additional details. ---------- Thank-You! ---------- If you're trying GO for the first time, we'd like to thank you for your interest in our product, and for taking the time to evaluate it. If you're a registered owner, or you're planning on ordering a registered copy, we thank you for supporting the shareware concept; it's your support that makes it possible for shareware authors to continue producing affordable, quality software!